SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_qt.idb/usr/freeware/catman/p_man/cat3/qintcache.Z/qintcache

Text File | 1998-10-28 | 14.8 KB | 265 lines

     QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))    QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))



     NNNNAAAAMMMMEEEE
      QIntCache - Template class that provides a cache based on
      long keys

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
      #include <qintcache.h>

      Inherits QGCache.

    PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrrssss
      QQQQIIIInnnnttttCCCCaaaacccchhhheeee (((( ccccoooonnnnsssstttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc    ))))
      QQQQIIIInnnnttttCCCCaaaacccchhhheeee (((( iiiinnnntttt _m_a_x_C_o_s_t====111100000000,,,, iiiinnnntttt _s_i_z_e====11117777 ))))
      ~~~~QQQQIIIInnnnttttCCCCaaaacccchhhheeee ()
      QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>>&&&& ooooppppeeeerrrraaaattttoooorrrr==== (((( ccccoooonnnnsssstttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc ))))
      iiiinnnntttt mmmmaaaaxxxxCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      iiiinnnntttt ttttoooottttaaaallllCCCCoooosssstttt    (((()))) ccccoooonnnnsssstttt
      vvvvooooiiiidddd sssseeeettttMMMMaaaaxxxxCCCCoooosssstttt (((( iiiinnnntttt    mmmm ))))
      vvvviiiirrrrttttuuuuaaaallll uuuuiiiinnnntttt ccccoooouuuunnnntttt (((())))    ccccoooonnnnsssstttt
      uuuuiiiinnnntttt ssssiiiizzzzeeee (((()))) ccccoooonnnnsssstttt
      bbbboooooooollll iiiissssEEEEmmmmppppttttyyyy (((()))) ccccoooonnnnsssstttt
      bbbboooooooollll iiiinnnnsssseeeerrrrtttt ((((    lllloooonnnngggg _k,,,,    ccccoooonnnnsssstttt ttttyyyyppppeeee **** _d,,,,    lllloooonnnngggg _c
      bbbboooooooollll rrrreeeemmmmoooovvvveeee ((((    lllloooonnnngggg kkkk ))))
      ttttyyyyppppeeee****    ttttaaaakkkkeeee (((( lllloooonnnngggg kkkk ))))
      vvvviiiirrrrttttuuuuaaaallll vvvvooooiiiidddd cccclllleeeeaaaarrrr (((())))
      ttttyyyyppppeeee****    ffffiiiinnnndddd (((( lllloooonnnngggg _k,,,, bbbboooooooollll _r_e_f====TTTTRRRRUUUUEEEE )))) ccccoooonnnnsssstttt
      ttttyyyyppppeeee****    ooooppppeeeerrrraaaattttoooorrrr[[[[]]]] (((( lllloooonnnngggg kkkk )))) ccccoooonnnnsssstttt
      vvvvooooiiiidddd ssssttttaaaattttiiiissssttttiiiiccccssss (((()))) ccccoooonnnnsssstttt

     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      The QIntCache    class is a template class that provides    a
      cache    based on long keys.

      QIntCache is implemented as both a template and a macro
      class. Define    a template instance QIntCache<X> to create a
      cache    that operates on pointers to X,    or X*.

      A cache is a least recently used (LRU) list of cache items.
      Each cache item has a    cost. The sum of item costs,
      totalCost(), will not    exceed the maximum cache cost,
      maxCost(). If    inserting a new    item would cause the total
      cost to exceed the maximum cost, the least recently used
      items    in the cache are deleted.

      Apart    from insert, by    far the    most important function    is
      find() (which    also exists as operatior[]). This function
      looks    up an item, returns it,    and by default marks it    as
      being    the least recently used    item.

      There    are also methods to remove() an    object from the    cache
      and delete it, and to    take() an object out of    the cache
      without deleting it.




     Page 1                         (printed 9/22/98)






     QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))    QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      QIntCache, as    it must, takes over ownership of the items you
      insert. That implies that it will delete the items at    its
      discretion, and that you must    _n_o_t delete them. There is one
      exception, however: If the cost of an    object you try to
      insert() is higher than the allowed total cost of the    cache,
      insert() returns FALSE and in    this case you must delete the
      object yourself.

      In addition to totalCost() and maxCost()/setMaxCost(), there
      are access functions to obtain the number of items in    the
      cache    (count()), the size of the hash    array (size(), set
      using    the constructor) and whether the cache is empty    (you
      guessed it: isEmpty()). Finally, there is a statistics(),
      which    prints various cache statistics    on stdout.

      There    is also    a QIntCacheIterator which may be used to
      traverse the items in    the cache in arbritrary    order.

      See also: QIntCacheIterator, QCache and Collection Classes

     MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
     QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::QQQQIIIInnnnttttCCCCaaaacccchhhheeee (((( ccccoooonnnnsssstttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc ))))
      For internal use only.

     QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::QQQQIIIInnnnttttCCCCaaaacccchhhheeee (((( iiiinnnntttt    mmmmaaaaxxxxCCCCoooosssstttt====111100000000,,,, iiiinnnntttt ssssiiiizzzzeeee====11117777 ))))
      Constructs an    empty cache with maximum allowed total cost
      _m_a_x_C_o_s_t and optimized    to contain a bit less than _s_i_z_e    items.

     QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::~~~~QQQQIIIInnnnttttCCCCaaaacccchhhheeee (((())))
      Destroys the object and all objects in it.

     vvvvooooiiiidddd QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::cccclllleeeeaaaarrrr (((()))) [[[[vvvviiiirrrrttttuuuuaaaallll]]]]
      Removes all items from the cache, and    deletes    them.

      All cache iterators that operate this    on cache are reset.

      See also: remove() and take().

      Reimplemented    from QCollection.

     uuuuiiiinnnntttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ccccoooouuuunnnntttt (((()))) ccccoooonnnnsssstttt [[[[vvvviiiirrrrttttuuuuaaaallll]]]]
      Returns the number of    items in the cache.

      See also: totalCost().

      Reimplemented    from QCollection.

     ttttyyyyppppeeee **** QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ffffiiiinnnndddd (((( lllloooonnnngggg kkkk,,,, bbbboooooooollll rrrreeeeffff====TTTTRRRRUUUUEEEE )))) ccccoooonnnnsssstttt
      Returns the item associated with \ k,    or null    if the key
      does not exist in the    cache. If _r_e_f is TRUE (the default),
      the item is moved to the front of the    LRU list.




     Page 2                         (printed 9/22/98)






     QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))    QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      If there are two or more items with equal keys, then the one
      that was inserted last is returned.

     bbbboooooooollll QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::iiiinnnnsssseeeerrrrtttt (((( lllloooonnnngggg kkkk,,,, ccccoooonnnnsssstttt ttttyyyyppppeeee **** dddd,,,, lllloooonnnngggg cccc====1111,,,,    iiiinnnntttt
      pppp====0000 ))))
      Inserts the item _d into the cache with key _k,    cost (default
      1) and priority _p (default 0). Returns TRUE if it succeeds
      and FALSE if it fails.

      The cache's size is limited, and if the total    cost is    too
      high,    QIntCache will delete some of the least-used objects.

      WWWWaaaarrrrnnnniiiinnnngggg:::: If this function returns FALSE, you must delete _d
      yourself. Additionally, be very careful about    using _d    after
      calling this function, as any    other insertions into the
      cache, from anywhere in the application, or within Qt
      itself, could    cause the object to be discarded from the
      cache, and the pointer to become invalid.

     bbbboooooooollll QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::iiiissssEEEEmmmmppppttttyyyy (((())))    ccccoooonnnnsssstttt
      Returns TRUE if the cache is empty, or TRUE if there is at
      least    one object in it.

     iiiinnnntttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::mmmmaaaaxxxxCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      Returns the maximum allowed total cost of the    cache.

      See also: setMaxCost() and totalCost().

     QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>>&&&& QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ooooppppeeeerrrraaaattttoooorrrr==== (((( ccccoooonnnnsssstttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee<<<<ttttyyyyppppeeee>>>> &&&& cccc
      ))))
      For internal use only.

     ttttyyyyppppeeee **** QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ooooppppeeeerrrraaaattttoooorrrr[[[[]]]] (((( lllloooonnnngggg kkkk )))) ccccoooonnnnsssstttt
      Returns the item associated with _k, or null if _k does    not
      exist    in the cache, and moves    the item to the    front of the
      LRU list.

      If there are two or more items with equal keys, then the one
      that was inserted last is returned.

      This is the same as find( k, TRUE ).

      See also: find().

     bbbboooooooollll QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::rrrreeeemmmmoooovvvveeee (((( lllloooonnnngggg kkkk ))))
      Deletes the item associated with _k, and returns TRUE if the
      item was present in the cache    or FALSE if it was not.

      If there are two or more items with equal keys, then the one
      that was inserted last is is deleted.

      All iterators    that refer to the removed item are set to



     Page 3                         (printed 9/22/98)






     QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))    TTTTrrrroooollllllll TTTTeeeecccchhhh AAAASSSS ((((9999 JJJJuuuullllyyyy 1111999999998888))))    QQQQIIIInnnnttttCCCCaaaacccchhhheeee((((3333qqqqtttt))))



      point    to the next item in the    cache's    traversal order.

      See also: take() and clear().

     vvvvooooiiiidddd QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::sssseeeettttMMMMaaaaxxxxCCCCoooosssstttt    (((( iiiinnnntttt mmmm    ))))
      Sets the maximum allowed total cost of the cache to _m. If
      the current total cost is above _m, some items    are deleted
      immediately.

      See also: maxCost() and totalCost().

     uuuuiiiinnnntttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ssssiiiizzzzeeee (((()))) ccccoooonnnnsssstttt
      Returns the size of the hash array used to implement the
      cache. This should be    a bit bigger than count() is likely to
      be.

     ttttyyyyppppeeee **** QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ttttaaaakkkkeeee (((( lllloooonnnngggg kkkk ))))
      Takes    the item associated with _k out of the cache without
      deleting it, and returns a pointer to    the item taken out, or
      null if the key does not exist in the    cache.

      If there are two or more items with equal keys, then the one
      that was inserted last is taken.

      All iterators    that refer to the taken    item are set to    point
      to the next item in the cache's traversal order.

      See also: remove() and clear().

     iiiinnnntttt QQQQIIIInnnnttttCCCCaaaacccchhhheeee::::::::ttttoooottttaaaallllCCCCoooosssstttt (((()))) ccccoooonnnnsssstttt
      Returns the total cost of the    items in the cache. This is an
      integer in the range 0 to maxCost().

      See also:  setMaxCost().

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      hhhhttttttttpppp::::////////wwwwwwwwwwww....ttttrrrroooollllllll....nnnnoooo////qqqqtttt////qqqqiiiinnnnttttccccaaaacccchhhheeee....hhhhttttmmmmllll

     CCCCOOOOPPPPYYYYRRRRIIIIGGGGHHHHTTTT
      Copyright 1992-1997 Troll Tech AS.  See the LICENSE file
      included in the distribution for a complete license
      statement.

     AAAAUUUUTTTTHHHHOOOORRRR
      Generated automatically from the source code.










     Page 4                         (printed 9/22/98)